[fix] TypeError coming from suffix arg removed from sphinx v3.0.0 #55

CrossNox · 2020-04-06T14:44:06Z

Since 1.8.0, the suffix argument for app.add_source_parser() has been deprecated. And it is removed now.

Fix and mantain backwards compatibility for older sphinx versions.

Closes #51

jdemonasterio · 2020-04-06T15:31:19Z

m2r.py

+    try:
+        app.add_source_parser('.md', M2RParser)  # for older sphinx versions
+    except TypeError:
        app.add_source_suffix('.md', 'markdown')
        app.add_source_parser(M2RParser)


Not sure if add_source_parser and add_source_suffix should be treated differently altogether:

Suggested change

try:

app.add_source_parser('.md', M2RParser) # for older sphinx versions

except TypeError:

app.add_source_suffix('.md', 'markdown')

app.add_source_parser(M2RParser)

if hasattr(app, 'add_source_suffix'):

app.add_source_suffix('.md', 'markdown')

try:

app.add_source_parser('.md', M2RParser) # for older sphinx versions

except TypeError:

app.add_source_parser(M2RParser)

the m2r extension isn't compatible with v3.0; see miyakogi/m2r#55 for example

matthewfeickert · 2020-04-13T05:17:38Z

@miyakogi If you get time to review this it would be great.

The release of sphinx 3.0.0 removed some functions that's been deprecated since v1.4. This made the sphinx-extension 'm2r' break. We use m2r to include .md files in the sphinx-docs. Although a PR that seemingly solves the problem is proposed [1], the sole developer of m2r has not been active in a while. It's unknown when and if this fix will be merge and even if, having a dependency on a unmaintained project like m2r makes me feel a bit uneasy. The ideal action would be to use 'recommonmark' for our .md files. However, sphinx and recommonmark does not play nice when the .md files is out of directory, i.e. outside python/docs [2]. That leaves us with two options, either pinning the sphinx version < 3.0.0 and wait for better days, with regards better sphinx/recommonmarks support, or port the CHANGELOG to rst. As it's unknown whether [2] will actually see the day of light or not, porting seems most reasonable at this point in time. To mention it, there is a bias against using .rst for CHANGELOGs and READMEs in the community, with the main points being; 'people are generally more familiar. md' and '.md is easier and faster to write'. But with a already well-defined structure to our CHANGELOG, the overhead is minimal. [1] miyakogi/m2r#55 [2] sphinx-doc/sphinx#7000

The release of sphinx 3.0.0 removed some functions that's been deprecated since v1.4. This made the sphinx-extension 'm2r' break. We use m2r to include .md files in the sphinx-docs. Although a PR that seemingly solves the problem is proposed [1], the sole developer of m2r has not been active in a while. It's unknown when and if this fix will be merge and even if, having a dependency on a unmaintained project like m2r makes me feel a bit uneasy. The ideal action would be to use 'recommonmark' for our .md files. However, sphinx and recommonmark does not play nice when the .md files is out of directory, i.e. outside python/docs [2]. That leaves us with two options, either pinning the sphinx version < 3.0.0 and wait for better days, with regards better sphinx/recommonmarks support, or port the CHANGELOG to rst. As it's unknown whether [2] will actually see the day of light or not, porting seems most reasonable at this point in time. To mention it, there is a bias against using .rst for CHANGELOGs and READMEs in the community, with the main points being that people are generally more familiar with .md and that .md is easier and faster to write. But with a already well-defined structure to our CHANGELOG, the overhead is minimal. [1] miyakogi/m2r#55 [2] sphinx-doc/sphinx#7000

The release of sphinx 3.0.0 removed some functions that's been deprecated since v1.4. This made the sphinx-extension 'm2r' break. We use m2r to include .md files in the sphinx-docs. Although a PR that seemingly solves the problem is proposed [1], the sole developer of m2r has not been active in a while. It's unknown when and if this fix will be merge and even if, having a dependency on a unmaintained project like m2r makes me feel a bit uneasy. The ideal action would be to use 'recommonmark' for our .md files. However, sphinx and recommonmark does not play nice when the .md files is out of directory, i.e. outside python/docs [2]. That leaves us with two options, either pinning the sphinx version to <v3.0.0 and wait for better days, with regards to better sphinx/recommonmarks support, or port the CHANGELOG to rst. As it's unknown whether [2] will actually see the day of light or not, porting seems most reasonable at this point in time. To mention it, there is a bias against using .rst for CHANGELOGs and READMEs in the community, with the main points being that people are generally more familiar with .md and that .md is easier and faster to write. But with a already well-defined structure to our CHANGELOG, the overhead is minimal. [1] miyakogi/m2r#55 [2] sphinx-doc/sphinx#7000

in m2r: miyakogi/m2r#55) - add path in conf.py to find the nmodl module - removed various doxygen warnings due to unacceptable keywords in configuration files - adjust checkparent_visitor sphinx autodoc /copybrief - reduce the maxium number of processors used to build documentation (it was freezing my workstation)

- m2r & sphinx>=3.0 are not compatible (more info in pr in progress in m2r: miyakogi/m2r#55) - add path in conf.py to find the nmodl module - removed various doxygen warnings due to unacceptable keywords in configuration files - adjust checkparent_visitor sphinx autodoc /copybrief - reduce the maxium number of processors used to build documentation (it was freezing my workstation)

- m2r & sphinx>=3.0 are not compatible (more info in pr in progress in m2r: miyakogi/m2r#55) - add path in conf.py to find the nmodl module - removed various doxygen warnings due to unacceptable keywords in configuration files - adjust checkparent_visitor sphinx autodoc /copybrief - reduce the maxium number of processors (freezed some workstations) - mistune downgrade due to conflicts with nbconvert Co-Authored-By: Omar Awile <[email protected]>

basnijholt · 2020-06-22T15:19:08Z

@miyakogi ping. No project that uses m2r builds using the latest Sphinx.
This includes all projects on Readthedocs.io (that use m2r).

sbliven · 2020-06-29T07:59:39Z

@basnijholt You can try @qhua948's fork, published as m2rr.

CrossNox · 2020-07-12T01:40:21Z

I've finally released my fork as m2r2 after revamping some of the tooling and building CD and testing pipelines.

basnijholt · 2020-08-03T14:41:18Z

Any comments on how https://github.com/qhua948/m2rr and https://github.com/CrossNox/m2r2 differ? Maybe only time will tell us which one will be maintained 😄

Until Sphinx upstream moves to a different markdown converter, m2r2 would fix builds. Issue: sphinx-doc/sphinx#7420 See also: miyakogi/m2r#55 (comment)

axsaucedo · 2020-08-28T10:53:12Z

This is great, thanks guys, will make a massive difference once it's merged. I'm now using m2r2 and seems to work quite well 👍

codecov-io · 2020-12-01T17:12:59Z

Codecov Report

Merging #55 (ee7c818) into dev (66f4a5a) will increase coverage by 0.13%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##              dev      #55      +/-   ##
==========================================
+ Coverage   96.14%   96.27%   +0.13%     
==========================================
  Files           3        3              
  Lines         778      779       +1     
==========================================
+ Hits          748      750       +2     
+ Misses         30       29       -1

Impacted Files	Coverage Δ
m2r.py	`93.59% <100.00%> (+0.32%)`	⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 66f4a5a...ee7c818. Read the comment docs.

suffix arg removed from sphinx v3.0.0

ee7c818

jdemonasterio reviewed Apr 6, 2020

View reviewed changes

This was referenced Apr 6, 2020

Bug Report: Sphinx v3.0.0 breaks docs build scikit-hep/pyhf#818

Closed

TypeError: add_source_parser() positional arguments error in Sphinx v3.0.0 sphinx-doc/sphinx#7420

Closed

bdewilde added a commit to chartbeat-labs/textacy that referenced this pull request Apr 9, 2020

Add upper bound to sphinx version

57baed6

the m2r extension isn't compatible with v3.0; see miyakogi/m2r#55 for example

This was referenced Apr 10, 2020

ENH: New devices pcdshub/pcdsdevices#400

Merged

m2r is broken pcdshub/pcdsdevices#410

Closed

jklaise mentioned this pull request Apr 14, 2020

Pin sphinx version to avoid m2r/sphinx bugs SeldonIO/alibi#208

Merged

daniellimws mentioned this pull request Apr 17, 2020

Update documentation for clock examples chipsalliance/f4pga-v2x#42

Merged

ErlendHaa mentioned this pull request Apr 17, 2020

Port CHANGELOG.md -> CHANGELOG.rst equinor/dlisio#254

Merged

This was referenced Apr 22, 2020

Bugfixes for documentation build (issues #305, 307) BlueBrain/nmodl#308

Closed

Bugfixes for documentation build (issues #305, 307) BlueBrain/nmodl#309

Merged

daniellimws mentioned this pull request Apr 27, 2020

Create a symbiflow-sphinx-docs-common repository f4pga/ideas#49

Open

4 tasks

ZaxR mentioned this pull request May 30, 2020

hotfix docs building issue by pinning Sphinx v2.x.x ZaxR/bulwark#79

Merged

espdev mentioned this pull request Jun 12, 2020

Update sphinx requirement from <3,>=2.3 to >=2.3,<4 espdev/csaps#23

Closed

orangecms added a commit to orangecms/pslab-documentation that referenced this pull request Aug 9, 2020

Use m2r2 for now to fix build

c10ea1f

Until Sphinx upstream moves to a different markdown converter, m2r2 would fix builds. Issue: sphinx-doc/sphinx#7420 See also: miyakogi/m2r#55 (comment)

orangecms added a commit to fossasia/pslab-documentation that referenced this pull request Aug 9, 2020

Use m2r2 for now to fix build

4a34f50

Until Sphinx upstream moves to a different markdown converter, m2r2 would fix builds. Issue: sphinx-doc/sphinx#7420 See also: miyakogi/m2r#55 (comment)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[fix] TypeError coming from suffix arg removed from sphinx v3.0.0 #55

[fix] TypeError coming from suffix arg removed from sphinx v3.0.0 #55

CrossNox commented Apr 6, 2020

jdemonasterio Apr 6, 2020

matthewfeickert commented Apr 13, 2020

basnijholt commented Jun 22, 2020

sbliven commented Jun 29, 2020

CrossNox commented Jul 12, 2020

basnijholt commented Aug 3, 2020

axsaucedo commented Aug 28, 2020 •

edited

Loading

codecov-io commented Dec 1, 2020

[fix] TypeError coming from suffix arg removed from sphinx v3.0.0 #55

Are you sure you want to change the base?

[fix] TypeError coming from suffix arg removed from sphinx v3.0.0 #55

Conversation

CrossNox commented Apr 6, 2020

jdemonasterio Apr 6, 2020

Choose a reason for hiding this comment

matthewfeickert commented Apr 13, 2020

basnijholt commented Jun 22, 2020

sbliven commented Jun 29, 2020

CrossNox commented Jul 12, 2020

basnijholt commented Aug 3, 2020

axsaucedo commented Aug 28, 2020 • edited Loading

codecov-io commented Dec 1, 2020

Codecov Report

axsaucedo commented Aug 28, 2020 •

edited

Loading